/**
 * @file console_color.h
 * @brief 控制台颜色设置库
 * @details 提供控制台文本和背景颜色设置功能，支持16种文本颜色和8种背景颜色
 */

#ifndef __CONSOLE_COLOR_H__
#define __CONSOLE_COLOR_H__

/**
 * @defgroup TextColors 文本颜色定义
 * @brief 控制台文本颜色常量定义（0-15）
 * @{
 */
#define BLACK_TEXT      0   /**< 黑色文本 */
#define BLUE_TEXT       1   /**< 蓝色文本 */
#define GREEN_TEXT      2   /**< 绿色文本 */
#define CYAN_TEXT       3   /**< 青色文本 */
#define RED_TEXT        4   /**< 红色文本 */
#define MAGENTA_TEXT    5   /**< 品红色文本 */
#define BROWN_TEXT      6   /**< 棕色文本 */
#define LIGHTGRAY_TEXT  7   /**< 浅灰色文本 */
#define DARKGRAY_TEXT   8   /**< 深灰色文本 */
#define LIGHTBLUE_TEXT  9   /**< 浅蓝色文本 */
#define LIGHTGREEN_TEXT 10  /**< 浅绿色文本 */
#define LIGHTCYAN_TEXT  11  /**< 浅青色文本 */
#define LIGHTRED_TEXT   12  /**< 浅红色文本 */
#define LIGHTMAGENTA_TEXT 13 /**< 浅品红色文本 */
#define YELLOW_TEXT     14  /**< 黄色文本 */
#define WHITE_TEXT      15  /**< 白色文本 */
/** @} */

/**
 * @defgroup BackgroundColors 背景颜色定义
 * @brief 控制台背景颜色常量定义（0-240）
 * @{
 */
#define BLACK_BG        0   /**< 黑色背景 */
#define BLUE_BG         16  /**< 蓝色背景 */
#define GREEN_BG        32  /**< 绿色背景 */
#define CYAN_BG         48  /**< 青色背景 */
#define RED_BG          64  /**< 红色背景 */
#define MAGENTA_BG      80  /**< 品红色背景 */
#define BROWN_BG        96  /**< 棕色背景 */
#define LIGHTGRAY_BG    112 /**< 浅灰色背景 */
#define WHITE_BG        240 /**< 白色背景 */
/** @} */

/**
 * @brief 设置控制台文本和背景颜色
 * 
 * 该函数将指定的文本颜色和背景颜色组合应用到控制台输出。
 * 如果是首次调用，会自动初始化并保存默认控制台属性。
 * 
 * @param textColor 文本颜色值（0-15），使用 @ref TextColors "预定义的文本颜色常量"
 * @param backgroundColor 背景颜色值（0-240），使用 @ref BackgroundColors "预定义的背景颜色常量"
 * 
 * @return void
 * 
 * @note 文本颜色使用低4位（0x0F），背景颜色使用高4位（0xF0）
 * @warning 颜色值超出范围会被自动截断
 * @see ResetConsoleColor()
 * 
 * @par 示例
 * @code
 * // 设置文本为红色，背景为黑色（默认）
 * SetConsoleColor(RED_TEXT, BLACK_BG);
 * printf("This text is red!\n");
 * 
 * // 设置文本为白色，背景为蓝色
 * SetConsoleColor(WHITE_TEXT, BLUE_BG);
 * printf("This text is white on blue background!\n");
 * @endcode
 */
void SetConsoleColor(int textColor, int backgroundColor);

/**
 * @brief 重置控制台颜色为初始状态
 * 
 * 该函数将控制台颜色恢复为首次调用SetConsoleColor时保存的默认颜色。
 * 
 * @return void
 * 
 * @note 若未调用过SetConsoleColor，此函数可能无效果
 * @see SetConsoleColor()
 */
void ResetConsoleColor();

/**
 * @brief 以指定颜色打印字符串（ANSI字符）
 * 
 * 该函数临时设置控制台文本颜色，打印字符串后恢复默认颜色。
 * 
 * @param textColor 文本颜色值（0-15）
 * @param text 要打印的字符串
 * 
 * @note 背景颜色固定为白色（WHITE_BG）
 * @see SetConsoleColor()
 */
void ColorfulPrintString(int textColor, char* text);

/**
 * @brief 以指定颜色打印宽字符
 * 
 * 该函数临时设置控制台文本颜色，打印宽字符后恢复默认颜色。
 * 
 * @param textColor 文本颜色值（0-15）
 * @param ch 要打印的宽字符
 * 
 * @note 背景颜色固定为白色（WHITE_BG）
 * @see SetConsoleColor()
 */
void ColorfulPrintWchar(int textColor, wchar_t ch);

#endif // __CONSOLE_COLOR_H__